Skip to content

docs: sync from cloudflare/agents PR #731 - refactor tools #27094

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
agents-git-bot wants to merge 1 commit into
base: production
Choose a base branch
from
Open

docs: sync from cloudflare/agents PR #731 - refactor tools #27094

agents-git-bot wants to merge 1 commit into from

Conversation

@agents-git-bot
Copy link
Contributor

@agents-git-bot agents-git-bot bot commented Dec 12, 2025 •
edited
Loading

Summary

This PR syncs documentation updates from cloudflare/agents PR #731 which introduces breaking changes to the Agents SDK's tool and chat APIs.

Changes

  • Breaking: Replace useAgent + useAgentChat two-hook pattern with unified useChat hook
  • Breaking: New declarative tool configuration using confirm and execute properties
  • Breaking: Simplified approval API with approve(id) and deny(id) instead of addToolResult()
  • Add documentation for TOOL_CONFIRMATION protocol constants
  • Update human-in-the-loop guide with complete examples using new API
  • Update Agents API reference with new useChat hook documentation

Source PR

Breaking Changes

These changes affect how users implement human-in-the-loop workflows:

Old pattern (deprecated):

const agent = useAgent({ agent: "my-agent" });
const { messages, sendMessage, addToolResult } = useAgentChat({
  agent,
  tools: clientTools,
  toolsRequiringConfirmation: ["toolA", "toolB"]
});
// Manual approval handling
addToolResult({ tool: "toolA", output: "Yes, confirmed.", toolCallId });

New pattern:

const { messages, sendMessage, approve, deny, pendingToolCalls } = useChat({
  agent: "my-agent",
  tools: clientTools // confirm property defines approval behavior
});
// Simple approval handling
approve(toolCallId);

Impact

  • All users implementing human-in-the-loop workflows will need to migrate to the new API
  • Tool configuration is now declarative with confirm: true/false instead of manual tracking lists
  • Significantly simpler API surface for common use cases

🤖 Generated with Claude Code

@github-actions github-actions bot added product:agents Build and deploy AI-powered Agents on Cloudflare that can act autonomously. size/l labels Dec 12, 2025
@github-actions
Copy link
Contributor

github-actions bot commented Dec 12, 2025

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern Owners
/src/content/docs/agents/ @irvinebroque, @rita3ko, @elithrar, @thomasgauvin, @threepointone, @whoiskatrin, @cloudflare/pcx-technical-writing, @cloudflare/ai-agents

@agents-git-bot agents-git-bot bot changed the title refactor tools Sync docs for PR #731: refactor tools Dec 12, 2025
@agents-git-bot agents-git-bot bot changed the title Sync docs for PR #731: refactor tools Sync docs for PR #731: refactor tools (useChat hook + declarative tools) Dec 12, 2025
@agents-git-bot agents-git-bot bot force-pushed the sync-docs-pr-731 branch 3 times, most recently from de01ade to d7c601b Compare December 12, 2025 19:08
@github-actions
docs: update for useChat hook refactor (PR #731)
2133fe0 
Updates documentation to reflect the breaking changes in PR #731:
- Replace useAgent + useAgentChat two-hook pattern with unified useChat hook
- Update human-in-the-loop guide with new declarative tool configuration
- Document new approve(id)/deny(id) API replacing addToolResult()
- Add TOOL_CONFIRMATION protocol constants documentation
- Update tool configuration to use confirm property instead of manual lists
- Simplify examples to show new streamlined API

This is a breaking change that affects how users implement human-in-the-loop
workflows with the Agents SDK.

Related PR: cloudflare/agents#731
@agents-git-bot agents-git-bot bot changed the title Sync docs for PR #731: refactor tools (useChat hook + declarative tools) docs: sync from cloudflare/agents PR #731 - refactor tools Dec 12, 2025
@github-actions
Copy link
Contributor

github-actions bot commented Dec 12, 2025

Preview URL: https://2133fe07.preview.developers.cloudflare.com
Preview Branch URL: https://sync-docs-pr-731.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link Updated Link
https://developers.cloudflare.com/agents/guides/human-in-the-loop/ https://sync-docs-pr-731.preview.developers.cloudflare.com/agents/guides/human-in-the-loop/
https://developers.cloudflare.com/agents/api-reference/agents-api/ https://sync-docs-pr-731.preview.developers.cloudflare.com/agents/api-reference/agents-api/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@irvinebroque irvinebroque Awaiting requested review from irvinebroque irvinebroque is a code owner

@rita3ko rita3ko Awaiting requested review from rita3ko rita3ko is a code owner

@elithrar elithrar Awaiting requested review from elithrar elithrar is a code owner

@thomasgauvin thomasgauvin Awaiting requested review from thomasgauvin thomasgauvin is a code owner

@threepointone threepointone Awaiting requested review from threepointone threepointone is a code owner

@whoiskatrin whoiskatrin Awaiting requested review from whoiskatrin whoiskatrin is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

@elithrar elithrar

@threepointone threepointone

@irvinebroque irvinebroque

@rita3ko rita3ko

@whoiskatrin whoiskatrin

@thomasgauvin thomasgauvin

Labels

product:agents Build and deploy AI-powered Agents on Cloudflare that can act autonomously. size/l

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

6 participants

@elithrar @threepointone @irvinebroque @rita3ko @whoiskatrin @thomasgauvin